PocketDING
==========

This program is a version of Ding (http://www-user.tu-chemnitz.de/~fri/ding/) which can be
executed on PDAs. It scans a dictionary file for a search pattern entered by the user and
outputs all entries that match.


Installation
------------

Choose one of the following alternatives to install the program on your PDA:

- Connect PDA and PC and execute PocketDING-Setup.exe on the PC.
- Or open PocketDING.CAB on the PDA.
- Or copy PocketDING.exe to the PDA und create a shortcut manually.

PLEASE NOTE: This program needs a word list which can be downloaded from the following
internet address:

  http://ftp.tu-chemnitz.de/pub/Local/urz/ding/de-en/

Take care that the file's name is "de-en.txt" and it is located in the same folder as this
program. If you want to store this big file at another place (f.e. memory card) then you
will have to create and configure an INI file (see below for details). You can do this
manually by using a file manager and a text editor, but it's much more comfortable to do
this by simply executing the following 5 steps.


Add Dictionaries
----------------

Click on the menu item "File::Settings" if you want to use multiple dictionaries.
Execute the following steps to add a new dictionary to PocketDING:

1. Copy a dictionary file that is in DING format to the PDA. The destination should be a
   folder which is accessible via the open file dialog.

2. Open PocketDING.exe, then click on the menu item "File::Settings".

3. Click on the add button and select the dictionary file. After that its filename is
   shown in the dictionary list.

4. Switch to the other tabs and configure the settings for the added dictionary.

5. Switch back to the first tab (e.g. by tapping on the small X-button in the upper right
   corner of the dialog window) and then press the OK button to save the settings. Or
   click on the cancel button to close the settings dialog without saving any changes.

PocketDING makes the dictionary which is selected while the settings dialog is closed to
the current dictionary. That dictionary becomes the first item in the dictionary list.


Use LingoPad Dictionaries with PocketDING
-----------------------------------------

If there is LingoPad (http://www.ego4u.de/en/lingopad) installed on your PC, you can use
its dictionary files with PocketDING. In the program folder or user folder of LingoPad
there is a subfolder named "data" containing files of type TDB. Copy such a dictionary
file to your PDA and then continue with step 2 described above.

The LingoPad file format is very close to DING file format, so the content of a TDB file
can be converted on-the-fly while scanning it. Note the terms of usage and comply with the
licence agreements which come with LingoPad dictionaries!


Convert other dictionaries to DING format
-----------------------------------------

With the windows program ConvDING you can convert CSV/Excel files, FreeDict dictionaries
(http://www.freedict.org/) and StarDict dictionaries (http://stardict.sourceforge.net) to
DING format. Such a converted file can be used by PocketDING or LingoPad.


Scanning the Dictionary
-----------------------

After tapping the search item on the menu bar a dialog window opens. Enter a search
pattern, then press the search button to start a full-text search on the word list. Even
on a fast PDA this will need some seconds but as soon as matchings are found they are
printed out while the search process continues. However, at any time you can tap the
cancel item on the menu bar to abort the scan. The abbreviations used in the search result
are described here:

  http://dict.tu-chemnitz.de/de-en/abb.en.html

In the search dialog you can check the options "Beginning of Line", "Beginning of Word",
"End of Word" and/or "Case Sensitive" to avoid getting result lists which are too large.
Alternatively you can decrease the value given for the maximum number of hits. Select ">>"
if you want to search the pattern in the source language only; if "<<" is selected then
the pattern will only be searched in the target language.


Using the Clipboard
-------------------

If you tap-and-hold the stylus on the search expression control in the search dialog a
pop-up menu will open containing the (clipboard) items Cut, Copy, Paste and Delete.
Additionally the last five search expressions are appended to this menu and can be re-used
by clicking on them. Note that this search history isn't saved, so these items will get
lost if you exit the program via "File::Exit".

Hold the stylus on the search result and drag across the screen to select a text. While
there is a selection in the output area of PocketDING you can

- press the search item to open the search dialog and initialize the search expression
  control with the selected text, or
- tap-and-hold the stylus to open a pop-up menu which allows you to copy the selected text
  to the clipboard or append it to the scratchpad (see below for details).

If you tap on the display shortly or scroll the window then an existing selection will be
cleared.


Using the Scratchpad
--------------------

In the scratchpad you can store parts of search results which are worth to archive.
Initially you have to create an empty scratchpad file via "File::Scratchpad::Create".
After that you can select text in the output area, then tap-and-hold the stylus to open
the pop-up menu and click the item "Append to Scratchpad" to append the selected text to
the existing scratchpad content. The current content of the scratchpad will be displayed
in the output area after clicking the menu item "File::Scratchpad::Show". Use
"File::Scratchpad::Clear" to erase the content of the scratchpad file and
"File::Scratchpad::Delete" to delete it.

Every dictionary uses its own scratchpad file. It's a text file located in the same folder
as the currently loaded dictionary. Its filename is the same as the dictionaries one but
extended by "_pad.txt". DING format is used for scratchpad content, so every line in the
scratchpad file has the form "<source language> :: <target language>". Therefore your
selection should always cover a complete translation line in the search result, e.g.

  bird
    Vogel {m}

where "bird" is the source part and "Vogel {m}" is the target part. If your selection ends
within the source language then the search expression will be used as target part
automatically; if it begins within the target language then the search expression will be
used as source part.

There isn't any functionality in PocketDING to edit scratchpad content. Instead it's
recommended to export the content (which is currently displayed in PocketDINGs output
area) by selecting the item "HTML" or "CSV" in the submenu "File::Export" and then clear
the scratchpad via "File::Scratchpad::Clear". The exported data can be used with other
applications, e.g. to build up a vocabulary list for language training consisting of
translations you have looked up in PocketDING. OpenOffice.org Calc and most other
spreadsheet applications are able to import CSV ("Comma Separated Values"), so you can use
them to merge and manage your exported data on the PC. In the import dialogs of these
programs you should set the comma (,) as separator, the quote (") as string delimiter and
select the same charset as used in your dictionary file (either UTF-8 or ISO-8859-1).


The INI File
------------

You can customize PocketDING by creating a text file named PocketDING.ini in the program's
folder (where PocketDING.exe is located). Each line in this INI file must look like this:

  <keyword>=<value>

In the expression above <keyword> is one of the following keywords and <value> is a
numeric value or a string which you want to assign to the keyword:

- "CaseSensitive":
  If value is not 0 then the option "Case Sensitive" will be checked in the search dialog
  when starting the program.
- "DataBase":
  A file path and name specifying a word list file must be assigned to this keyword. Then
  the program uses that file as word list instead of searching the program's folder for a
  file named "de-en.txt". If the value assigned to the keyword does not contain a
  backslash then the path to the program's folder will be put in front of the value.
- "FontSize":
  A value between 8 and 24 must be assigned to this keyword. By doing this you can set the
  font size for the program.
- "LineBegin":
  If value is not 0 then the option "Beginning of Line" will be checked in the search
  dialog when starting the program.
- "MaxHits":
  A value between 1 and 9999 must be assigned to this keyword. The edit field titled
  "Maximum Number of Hits" in the search dialog is initialized with this value. Otherwise
  the default value for this field is 99.
- "OpenDialog":
  If value is not 0 then the search dialog will open automatically when starting the
  program.
- "OutputFormat":
  If value is 1 then the background color won't be toggled in the search result. Increment
  the preferred value by 2 if you don't want the target language to be printed in italics.
  Increment the value by 4 to suppress indentation for the target language.
- "SearchDirection":
  If value is 0 then the search direction will be set to "<>". The value 1 selects the
  item ">>", and "<<" is selected by the value 2.
- "StartMessage":
  Normally the file path and name to the word list is displayed on the message bar when
  the program is started or the search dialog is opened. But this start message can be
  customized by assigning another text to this keyword.
- "SwitchLanguage":
  If value is 0 then the program will use the English language; if value is 1 then the
  program will use the German language. The program's default language depends on the
  region settings choosen for the PDA. Increment the preferred value by 2 if you want to
  swap the order of the language in the search result. Increment the value by 4 if the
  word list is not in UNICODE format. For word lists in DING format the value assigned to
  the keyword should not be greater than 7, but add 512 to the value for LingoPad
  dictionaries!
- "WordBegin":
  If value is not 0 then the option "Beginning of Word" will be checked in the search
  dialog when starting the program.
- "WordEnd":
  If value is not 0 then the option "End of Word" will be checked in the search dialog
  when starting the program.

If you configured PocketDING via the menu item "File::Settings" you may notice that some
lines are grouped in the INI file. Each group begins with an identifier enclosed in
brackets and contains the settings for a dictionary.

By default PocketDING uses ISO-8859-1 decoding when reading the INI file. If the content
of the INI file is UTF-8 encoded then its content should begin with the character sequence
"#!UTF-8"! If you enter non-ISO-8859-1 characters (e.g. the Euro currency symbol) in the
settings dialog then the INI file will be saved in UTF-8 format automatically; otherwise
the encoding remains unchanged.

The program can be opened with the path and name of an INI file as parameter. So if there
is more than one word list on your PDA you could create multiple shortcuts which call the
program with the right INI file as argument. Enclose the parameter into quotes if it
contains spaces. You must quit an existing instance of the program via the menu item
"File::Exit" before a new one can be opened.


Create a Portable App
---------------------

PocketDING does not use the windows registry but stores all its settings in an INI file.
To create a portable application take care that the INI file is named PocketDING.ini and
is located in the program's folder; additionally put all your dictionary files also into
the program's folder and assign only filenames without paths to each keyword "Database="
in the INI file.


Related Projects and Software
-----------------------------

- Ding [ http://www-user.tu-chemnitz.de/~fri/ding/ ]
- MacDING [ http://macding.sourceforge.net/ ]
- MobileDing [ http://www.sebastianbauer.info/index.php?page=mobileding ]
- LingoPad [ http://www.ego4u.de/en/lingopad ]
- BEOLINGUS [ http://dict.tu-chemnitz.de/ ]


Dictionaries in Ding Format
---------------------------

- German-English [ http://ftp.tu-chemnitz.de/pub/Local/urz/ding/de-en/ ]
                 [ http://ftp.tu-chemnitz.de/pub/Local/urz/ding/de-en-devel/ ]
- German-Norwegian [ http://macding.sourceforge.net/ ]
- German-Spanish [ http://savannah.nongnu.org/projects/ding-es-de/ ]


License and Warranty
--------------------

PocketDING is free software; you can redistribute and/or modify it under the terms of the
GNU General Public License Version 2 (or any later version) published by the Free Software
Foundation. This program is distributed in the hope that it will be useful, but without
any warranty. Refer to the GNU General Public License for more details:
http://www.fsf.org/copyleft/gpl.html#SEC1

In addition to the terms of the license mentioned above, everybody is allowed to use
his/her own contributions to the PocketDING project (e.g. self-written code) also in works
(e.g. projects, programs) licensed in an other way, if these own contributions can be
separated clearly from contributions made by others and if the free use of PocketDING and
its source code in accordance with the GNU General Public License is not affected.


Contact and Download Location
-----------------------------

- http://freenet-homepage.de/martin_wehner/
- mailto:martin_wehner@freenet.de


History
-------

[1.2.1 2008-04-24]
  - Scratchpad menu item now is disabled if no word list is loaded
  - Fixed: Flag for reverse output now is ignored if scratchpad content is shown
  - Other modifications and improvements
[1.2.0 2008-03-03]
  - Scratchpad functionality added
  - Selections on the search result are now supported
  - Pop-up menus added (for most edit fields and search result)
  - Search expression history added (in the search expression pop-up menu)
  - Clipboard functionality added (Cut, Copy, Past and Delete items in the pop-up menus)
  - CSV export added
  - The file menu has been re-designed
  - Now the UTF-8 Byte-Order Mark (BOM) EF BB BF is skipped when reading a text file
  - Other improvements and modifications
[1.1.2 2007-10-10]
  - Now unicode is supported in INI file
  - Added tab "Search Result" with new formatting options to settings dialog
  - Added keyword "OutputFormat" for new formatting options to configuration language
  - Moved controls for font size from tab "Other" to tab "Search Result"
  - Now response is much better when a lot of output is written while searching
  - Size of internal line buffer has been increased from 4 KB up to 64 KB
  - Fixed: Now scrolling works fine even for more than 32767 rows
[1.1.1 2007-09-20]
  - Handling of the settings dialog is now more intuitive
  - Now first the settings are saved into temporary file which then replaces the original
  - Internal modifications and improvements
  - Fixed: Dictionaries couldn't be read from subfolders if a relative path was specified
  - Fixed: In settings dialog the last changes were ignored when add button was pressed
  - Fixed: Bigger values for "Maximum Number of Hits" weren't read from INI file
[1.1.0 2007-08-31]
  - Added settings dialog
  - Now multiple databases can be handled
  - Now start message is displayed in message bar while search dialog is open
  - Fixed automatically opening of search dialog while restoring from minimized state
  - Internal modifications and improvements
[1.0.3 2007-04-25] (unreleased)
  - Added support for LingoPad dictionaries
  - Internal improvements (e.g. unicode handling)
  - Now the file path can be omitted in the value assigned to keyword "DataBase"
  - Search dialog now also opens automatically when existing instance is reopened
[1.0.2 2007-04-04]
  - Added "<", ">" and quotes to the group of word separators
  - HTML export now handles reserved characters "&", "<" and ">"
  - Keyword "SearchDirection" replaces "SetDirection" in INI file
  - Internal improvements
[1.0.1 2007-03-31]
  - Added "{" and "}" to the group of word separators
  - Fixed mismatch between search direction and language setting
[1.0.0 2007-03-27]
  - First release
